home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection Student Program / ADC Tools Sampler CD Disk 3 1999.iso / Metrowerks CodeWarrior / Java Support / Java_Source / Java2 / src / javax / swing / Action.java < prev    next >
Encoding:
Java Source  |  1999-05-28  |  6.5 KB  |  162 lines  |  [TEXT/CWIE]
  1. /*
  2.  * @(#)Action.java    1.14 98/08/26
  3.  *
  4.  * Copyright 1997, 1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  *
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package javax.swing;
  15.  
  16. import java.awt.*;
  17. import java.awt.event.*;
  18. import java.beans.*;
  19.  
  20. /**
  21.  * The JFC Action interface provides a useful extension to the ActionListner
  22.  * interface in cases where the same functionality may be accessed by
  23.  * several controls.
  24.  * <p>
  25.  * In addition to the <code>actionPerformed</code> method
  26.  * defined by the ActionListener interface, this interface allows the
  27.  * application to define, in a single place:
  28.  * <ul>
  29.  * <li>One or more text strings that describe the function. These strings
  30.  *     can be used, for example, to display the flyover text for a button
  31.  *     or to set the text in a menu item.
  32.  * <li>One or more icons that depict the function. These icons can be used
  33.  *     for the images in a menu control, or for composite-entries in a more
  34.  *     sophisticated user-interface.
  35.  * <li>The enabled/disabled state of the functionality. Instead of having
  36.  *     to separately disable the menu-item and the toolbar-button, the
  37.  *     application can disable the function that implements this interface.
  38.  *     All components which are registered as listeners for the state-change
  39.  *     then know to disable event-generation for that item and to modify the 
  40.  *     display accordingly.
  41.  * </ul>
  42.  * Containers in the Swing set like menus and toolbars know how to add an
  43.  * Action object, as well as other components, using a version of the 
  44.  * <code>add</code> method. When an Action object is added to such a
  45.  * container, the container:
  46.  * <ol type="a">
  47.  * <li>Creates a component that is appropriate for that container 
  48.  *     (a toolbar creates a button component, for example).
  49.  * <li>Gets the appropriate property(s) from the Action object to customize
  50.  *     the component (for example, the icon image and flyover text).
  51.  * <li>Checks the intial state of the Action object to determine if it is
  52.  *     enabled or disabled, and renders the component in the appropriate
  53.  *     fashion.
  54.  * <li>Registers a listener with the Action object so that is notified of
  55.  *     state changes. When the Action object changes from enabled to disabled,
  56.  *     or back, the container makes the appropriate revisions to the
  57.  *     event-generation mechanisms and renders the component accordingly.
  58.  * </ol>
  59.  * For example, both a menu item and a toolbar button could access a
  60.  * <code>Cut</code> action object. The text associated with the object is 
  61.  * specified as "Cut", and an image depicting a pair of scissors is specified 
  62.  * as its icon. The <code>Cut</code> action-object can then be added to a
  63.  * menu and to a toolbar. Each container does the appropriate things with the
  64.  * object, and invokes its <code>actionPerformed</code> method when the
  65.  * component associated with it is activated. The application can then disable 
  66.  * or enable the application object without worrying about what user-interface
  67.  * components are connected to it.
  68.  * <p>
  69.  * This interface can be added to an existing class or used to create an
  70.  * adapter (typically, by subclassing AbstractAction). The Action object
  71.  * can then be added to multiple action-aware containers and connected to
  72.  * Action-capable components. The GUI controls can then be activated or
  73.  * deactivated all at once by invoking the Action object's <code>setEnabled</code>
  74.  * method.
  75.  *
  76.  * @version 1.14 08/26/98
  77.  * @author Georges Saab
  78.  * @see AbstractAction
  79.  */
  80. public interface Action extends ActionListener {
  81.     /**
  82.      * Useful constants that can be used as the storage-retreival key 
  83.      * when setting or getting one of this object's properties (text
  84.      * or icon).
  85.      */
  86.     public static final String DEFAULT = "Default";
  87.     /** 
  88.      * The key used for storing the name for the action,
  89.      * used for a menu or button.
  90.      */
  91.     public static final String NAME = "Name";
  92.     /**
  93.      * The key used for storing a short description for the action,
  94.      * used for tooltip text.
  95.      */
  96.     public static final String SHORT_DESCRIPTION = "ShortDescription";
  97.     /**
  98.      * The key used for storing a longer description for the action,
  99.      * could be used for context-sensitive help.
  100.      */
  101.     public static final String LONG_DESCRIPTION = "LongDescription";
  102.     /**
  103.      * The key used for storing a small icon for the action,
  104.      * used for toolbar buttons.
  105.      */
  106.     public static final String SMALL_ICON = "SmallIcon";
  107.  
  108.     /**
  109.      * Gets one of this object's properties
  110.      * using the associated key.
  111.      * @see #putValue
  112.      */
  113.     public Object getValue(String key);
  114.     /**
  115.      * Sets one of this object's properties
  116.      * using the associated key. If the value has
  117.      * changed, a PropertyChangeEvent is sent
  118.      * to listeners.
  119.      *
  120.      * @param key    a String containing the key
  121.      * @param value  an Object value
  122.      */
  123.     public void putValue(String key, Object value);
  124.  
  125.     /**
  126.      * Tests the enabled state of the Action. When enabled,
  127.      * any component associated with this object is active and
  128.      * able to fire this object's <code>actionPerformed</code> method.
  129.      * If the value has changed, a PropertyChangeEvent is sent
  130.      * to listeners.
  131.      *
  132.      * @param  b true to enable this Action, false to disable it
  133.      */
  134.     public void setEnabled(boolean b);
  135.     /**
  136.      * Sets the enabled state of the Action. When enabled,
  137.      * any component associated with this object is active and
  138.      * able to fire this object's <code>actionPerformed</code> method.
  139.      *
  140.      * @return true if this Action is enabled
  141.      */
  142.     public boolean isEnabled();
  143.  
  144.     /**
  145.      * Add a PropertyChange listener. Containers and attached
  146.      * components use these methods to register interest in this Action
  147.      * object. When its enabled state or other property changes,
  148.      * the registered listeners are informed of the change.
  149.      *
  150.      * @param listener  a PropertyChangeListener object ...
  151.      */
  152.     public void addPropertyChangeListener(PropertyChangeListener listener);
  153.     /**
  154.      * Remove a PropertyChange listener.
  155.      *
  156.      * @param listener  a PropertyChangeListener object ...
  157.      * @see #addPropertyChangeListener
  158.      */
  159.     public void removePropertyChangeListener(PropertyChangeListener listener);
  160.  
  161. }
  162.